/*
 * Copyright (C) 2012 TopCoder Inc., All Rights Reserved.
 */
package com.ibm.dst.capacity.services;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;

import com.ibm.dst.capacity.entities.dao.XSeriesCapacity;
import com.ibm.dst.capacity.entities.dto.PagedResult;
import com.ibm.dst.capacity.entities.dto.ReportFormat;
import com.ibm.dst.capacity.entities.dto.XSeriesDetailedReportCriteria;
import com.ibm.dst.capacity.entities.dto.XSeriesSummaryReportCriteria;
import com.ibm.dst.capacity.entities.dto.XSeriesSummaryReportEntry;

/**
 * <p>
 * XSeriesReportService is the main interface of this component and provides service methods for generating xseries reports and handling data for xseries report. It provides methods for fetching the report contents for the xseries summary and detail report and also provides methods for persisting these report contents in either XML or CSV format. It also provides methods to import xseries capacity data from XML or CSV file and also ability to store xseries capacity data into persistence.
 * </p>
 * <p>
 * Thread-Safety: The implementation of this interface are expected to be thread-safe during the servicing of the service methods, once the initialization and configuration of the service class is done and the configuration values in the service class are not mutated during the servicing of the service methods.
 * </p>
 * @author fastprogrammer, TCSDEVELOPER
 * @version 1.0
 */
public interface XSeriesReportService {
    /**
     * <p>
     * Generates the XSeriesSummaryReport based on the passed criteria. If pageNo is 0 or less then all the results are fetched. If criteria is null then no criteria for filtering is applied.
     * </p>
     * Parameters:
     * ==========
     * criteria-  The XSeriesSummaryReportCriteria to be used for fetching the report.
     * pageNo:int - the page No for the page on which the entries needs to be fetched for the report.
     * pageSize:int - the size of the page.
     *
     * Return Value:
     * ============
     * PagedResult object for the set of XSeriesSummaryReportEntry
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if pageSize parameter is less than 1.
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * @param criteria
     * @param pageNo
     * @param pageSize
     * @return
     */
    public PagedResult<XSeriesSummaryReportEntry> getSummaryReport(XSeriesSummaryReportCriteria criteria, int pageNo,
        int pageSize);

    /**
     * <p>
     * Generates and writes XSeriesSummaryReport based on the passed criteria to the passed output stream in the format specified. If criteria is null then no criteria for filtering is applied.
     * </p>
     * Parameters:
     * ==========
     * criteria-  The XSeriesSummaryReportCriteria to be used for fetching the report.
     * reportFormat - the format of the report to be generated
     * output - the outputStream to which the report data has to be written.
     *
     * Return Value:
     * ============
     * None
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if pageSize parameter is less than 1.
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * XSeriesCapacityReportGenerationException: if there are issues in generating the report content or there are any I/O errors in writing the report.
     * @param criteria
     * @param reportFormat
     * @param output
     */
    public void generateSummaryReport(XSeriesSummaryReportCriteria criteria, ReportFormat reportFormat,
        OutputStream output);

    /**
     * <p>
     * Generates the XSeriesDetailedReport based on the passed criteria. If pageNo is 0 or less then all the results are fetched. If criteria is null then no criteria for filtering is applied.
     * </p>
     * Parameters:
     * ==========
     * criteria-  The XSeriesDetailedReportCriteria to be used for fetching the report.
     * pageNo:int - the page No for the page on which the entries needs to be fetched for the report.
     * pageSize:int - the size of the page.
     *
     * Return Value:
     * ============
     * PagedResult object for the set of XSeriesCapacity
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if pageSize parameter is less than 1.
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * @param criteria
     * @param pageNo
     * @param pageSize
     * @return
     */
    public PagedResult<XSeriesCapacity> getDetailedReport(XSeriesDetailedReportCriteria criteria, int pageNo,
        int pageSize);

    /**
     * <p>
     * Generates and writes XSeriesDetailedReport based on the passed criteria to the passed output stream in the format specified. If criteria is null then no criteria for filtering is applied.
     * </p>
     * Parameters:
     * ==========
     * criteria-  The XSeriesDetailedReportCriteria to be used for fetching the report.
     * reportFormat - the format of the report to be generated
     * output - the outputStream to which the report data has to be written.
     *
     * Return Value:
     * ============
     * None
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if pageSize parameter is less than 1.
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * XSeriesCapacityReportGenerationException: if there are issues in generating the report content or there are any I/O errors in writing the report.
     * @param criteria
     * @param reportFormat
     * @param output
     */
    public void generateDetailedReport(XSeriesDetailedReportCriteria criteria, ReportFormat reportFormat,
        OutputStream output);

    /**
     * <p>
     * Stores/Inserts the passes set of XSeriesCapacity records in persistence and performs auditing for each of the records.
     * </p>
     * Parameters:
     * ==========
     * records: the list of XSeriesCapacity data to insert.
     * byUser: the user performing the persist
     *
     * Return Value:
     * ============
     * None
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if any of the parameters are null or byUser parameter is an empty String or any of members in the records list is null.
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * @param records
     * @param byUser
     */
    public void insertCapacityData(List<XSeriesCapacity> records, String byUser);

    /**
     * <p>
     * Imports the XSeries Capacity data from the passed input stream [which can contain the data in either XML or CSV format] and stores the imported records in persistence.
     * </p>
     * Parameters:
     * ==========
     * inputStream: the stream from which the xseries capacity data needs to be imported.
     * byUser: the user performing the import
     *
     * Return Value:
     * ============
     * None
     *
     * Exceptions:
     * ==========
     * IllegalArgumentException: if any of the parameters are null or byUser parameter is an empty String or the inputStream is closed
     * PersistenceException: if there are any issues in the persistence handling.
     * XSeriesCapacityDataParsingException: if the content in the input stream is not in proper format as expect or there are any I/O exception when reading from input stream.
     * XSeriesReportServiceException: if there any other issues in performing the service.
     * @param input
     * @param byUser
     */
    public void importCapacityData(InputStream input, String byUser);
}

